The Users and Groups scripting addition is all about being able to manipulate your users and groups data file from AppleScript. When Apple shipped AppleShare 3.0 they also shipped a developers kit that allow developers access to the users and groups information maintained by the AppleShare server. This same library also works with Macintosh File Sharing. Unfortunately the library is only accessible from low level languages like Pascal and C. I wanted to change that so I wrote a scripting addition that allow you to manipulate users and groups files AppleScript.
Packing List
This archive contains the following files:
Users and Groups Read Me
This file.
Users and Groups
An AppleScript scripting addition for manipulating users and groups files.
GetUserList
An AppleScript that demonstrates a simple use of the Users and Groups scripting addition.
Installation
You can install the scripting addition by dragging it to the Scripting Additions folder inside the Extensions folder in your System Folder.
Using the Scripting Addition
The best way to find out how to use the scripting addition is to drop it on the Script Editor which will show you its dictionary. The dictionary contains buckets of comments and is very useful in finding out what commands are available.
One slight complication is the direct object, which is a file specification. The direct object is optional on all events except create users and groups. If you supply a file then the scripting addition uses it as the users and groups file to modify. If you don’t supply a file then the scripting addition uses the Users & Groups Data File (in the Preferences folder) by default.
One other slight complication is that get next user info and get next group info both return an empty record (ie {} ) if there is no next user/group. They do this because catching errors is such a pain in AppleScript and there’s no system wide null value. See the GetUserList script for an example of how to iterate over all users.
A further complication is the optional admin parameter passed to every command except create users and groups. On AppleShare File Servers the users and groups file is encrypted with the admin key and you must supply the admin key whenever you want to access the file. The admin parameter lets you supply an admin key where appropriate. For Macintosh File Sharing you should just leave out this parameter.
Some options are only available on AppleShare File Servers. These include:
o The save passwords, min password length, max failed logins and password expiry date parameters to the set users and groups info command and their corresponding fields in the users and groups record.
o The all privileges, change password and force password parameters to the create user and set user info commands and their corresponding fields in the user record.
o The number failed logins field in the user record.
If you try to set a value that is not support by this version of the users and groups file then the value is ignored. If you read a value that is not support then the value is undefined.
Living Dangerously
“What’s all this ‘dangerous hack’ business?” Well I’m glad you asked. Actually I’m not glad you asked but I guess I have to answer anyway.
All of the routines that modify the users and groups file take a boolean parameter called “dangerous hack” or “extremely dangerous hack”. To understand these parameters it is necssary to look at how the Users and Groups scripting addition works. It is based around a library, called the Users and Groups Library (UGL), that ships as part of the AppleShare 3.0 Developer’s Kit. This library was written by Apple and lets you do all the standard operations on users and groups files. Unfortunately it has the inconvenient restriction of only allowing you to modify the users and groups file when the file server is not running.
Needless to say this is kind of inconvenient. Well I got to thinking one day and asked myself “Why can’t you modify the users and groups file while the server is running? I mean, the Users & Groups control panel and AppleShare Admin both manage this feat.” So I went looking through the code in the UGL and found that there’s a blanket check for a running server when modify the file. I also looked through the Users & Groups control panel (well actually the Network Extension) and found that the code that modifies the users and groups file was very similar to that present in the UGL.
So what I did was simply hack out the server running check and replace it with one of my own. My check is conditional on the dangerous hack and extremely dangerous hack parameters to the scripting addition; it only comes into effect if you set one of those booleans. If you don’t set those booleans then the scripting addition is as safe as it ever was.
So when is it safe to set the dangerous hack and extremely dangerous hack parameters? Well for a start if you’re operating on a users and groups file that’s not the one in use by the file server then I can’t see you having any troubles. But what happens if you are modifying the one in use by the running file server. Well you face two dangers. Firstly, if the Users & Groups control panel or AppleShare Admin are open then you’re going to confuse them if you go tinkering with the users and groups file behind their back. So don’t set these parameters if the admin tools are open.
The second danger you face is more significant. If you set the extremely dangerous hack parameter then you can delete users/groups while the file server is running. This has the unfortunate consequence of leaving any folders that were owned by those users/groups orphaned. The Users & Groups control panel and AppleShare Admin both take steps to avoid this: they parse the entire folder structure reassigning the ownership of any folder that’s owned by the user/group. Seeing as this is a tricky operation I suggest that you never set the extremely dangerous hack parameter. That’s why I called it “extremely dangerous hack”.
All of this information is pure conjecture on my part. I have no intimate knowledge of the internals of the file server software. It is possible that I’m completely deluded and that setting either of these parameters will destroy your server. I can accept no responsibility for this. You have been warned.
Caveats
o Has only been tested with AppleScript 1.1. The old version worked fine under AppleScript 1.0 and I have no reason to expect this version won’t.
o I have tested the scripting addition with an AppleShare File Server 3.0 but, seeing as it’s not the primary test environment there may still be problems. I have no idea whether it works with later version of AppleShare, specifically AppleShare Pro. Please mail to me if you have any experience with this.
o The name parameter to set users and groups info does not change the name because I can’t figure out how to get the users and groups library to do it.
o You can’t set AppleShare File Server specific fields on a Macintosh File Sharing machine, even if you change the server version of the users and groups file. I presume this is a limitation of the users and groups library.
Creeping Legalitis
The software is the copyright of The University of Western Australia. It’s distributed as freeware, which means you can use it without payment in any project you like. The university is not responsible for anything it does (good or bad) to your users and groups file.
Version History
The original version (1.0b) of the Users and Groups addition was only released as part of Peter Lewis’s Script Daemon package. Peter needed a mechanism to authenticate using the Users & Groups Data File and I hacked together this scripting addition to do it. As well as the authenticate user command it had a pile of other commands that I never tested and only just worked.
Unfortunately a number of people took that version and started using it for other things and then had the audacity to report bugs in it! The bugs definitely weren’t a surprise to me; I’d never even tested most of the features of the previous version!!!
The next version (1.1b) represented a significant improvement over the previous version. Improvements over 1.0b include:
o All the fields in the users and groups record are now setup correctly.
o All the fields in the user record are now setup correctly.
o assign user to group now works.
o Compatible with international systems where the Users & Groups Data File is renamed.
o Fewer events. rename user/group have been replaced by options to set user/group info.
o Doesn’t “unimplemented trap” when File Sharing did not load at boot!
o Many other bug fixes.
This version (1.2b) has a hack in it that lets you (optionally) modify the users and groups information while the file server is running.
Credits
A big thanks must go to Marcus Jager <marcus@cs.uwa.edu.au> for his help sorting out the messy bits of the AppleScript interface. Good luck with your new job Jager!
I’ve also got to mention all those people who kept persecuting me with bug reports for the old version. If you hadn’t filled my mailbox with complaints I never would have got around to fixing this!
Secret Goodies
I have an unreleased HyperCard XCMD equivalent to the Users and Groups scripting addition. I didn’t include it in this release because it needs some work and with HyperCard 2.2 you can use the AppleScript scripting addition seemlessly from within HyperCard. If you’d like to see the XCMD released, let me know. You’d better have a good reason though (:
I didn’t release the source code to the Users and Groups scripting addition because it’s a little hard to separate from my libraries and you need the users and groups library (which is a saleable product) to build it. If you’d like access to the source code just drop me a line and I’ll see what I can do.
Contacts
I can be contacted at the following Internet Email address...
Quinn <quinn@cs.uwa.edu.au>
Please report any bugs you find in this software.
The latest version of the library should always be available from the following directory…
ftp://redback.cs.uwa.edu.au/Others/Quinn/
Please read the ReadMeAboutRedback file before getting files from Redback.
Conclusion
I would appreciate any feedback about the Users and Groups scripting additions. I always respond to my mail (eventually) so if you don’t get a reply then it’s either because your mail never made it to me or because my reply never made it to you.
